.\" Copyright (c) 2010 Marco Steinbach
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" The following requests are required for all man pages.
.Dd September 18, 2010
.\" .Os [OPERATING_SYSTEM] [version/release]
.Dt SQTOP 1
.Sh NAME
.Nm sqtop
.Nd display active client connections for Squid
.Sh SYNOPSIS
.Nm sqtop
.Op Ar options
.Sh DESCRIPTION
.Nm sqtop
displays information about currently active client connections for a Squid proxy
in a convenient way.
.Pp
Without options,
.Nm sqtop
tries to connect to a Squid proxy listening at 127.0.0.1 using port 3128. 
.Sh OPTIONS
.Bl -tag -width indent
.It Fl -help
Display a brief help text.
.It Fl -host Ar host ( Fl h Ar host )
Squid proxy host. Defaults to 127.0.0.1.
.It Fl -port Ar port ( Fl p Ar port )
Squid proxy port. Defaults to 3128.
.It Fl -pass Ar password ( Fl P Ar password )
Squid proxy cachemgr_passwd.
.It Fl -hosts Ar hostlist ( Fl H Ar hostlist )
Comma-separated list of client IP addresses (CIDR notation is supported) to query the
Squid proxy for. Hostnames are silently ignored.
.It Fl -users Ar userlist ( Fl u Ar userlist )
Comma-separated list of Squid usernames to list active connections for.
.It Fl -brief ( Fl b )
Display brief per-connection information, omits URLs.
.It Fl -detail ( Fl d )
Display detailed information (size, username and average speed) for each URL in each connection.
.It Fl -full ( Fl f )
Display full details (size, username, average speed, delay pool and elapsed time) for each URL in each connection.
.It Fl -zero ( Fl z )
Display zero values instead of silently omitting them.
.It Fl c
Don't compact the display of multiple occurrences of the same URL in a single connection.
.It Fl -once ( Fl o )
Disable interactive mode, just print statistics once to stdout.
.It Fl -refreshinterval Ar seconds ( Fl r Ar seconds )
Set the refresh-interval for interactive mode.
.It Fl n
Don't do hostname lookups.
.It Fl S
Don't strip domain part of hostname.
.El
.Sh INTERACTIVE MODE
If built with support for
.Xr ncurses 3 , 
.Nm
defaults to running in interactive mode, occupying the whole screen, unless the
.Ic --once
option was specified on the command line.
.Pp
Information about the Squid server currently connected to, the version of
.Nm
used, as well as eventual error messages are shown at the top of the display.
.Pp
The bottom of the display keeps various aggregates, including current and average speed, the total number of hosts connected and the total number of connections.
.Pp
Any option given on the command line can be changed from within interactive mode by pressing the key corresponding to its respective short option character.
.Pp
In addition to the options given on the command line,
.Nm
recognizes the following keys when in interactive mode:
.Bl -tag -width Fl
.It Ic /
Search for literal substrings in hosts, usernames or URLs.  Regular expressions are not parsed, currently.
.It Ic <space>
Stop refreshing.
.It Ic UP/DOWN, PGUP/PGDN, HOME/END
Scroll display.
.It Ic <enter>
Toggle displayed level of detail for the currently selected entry.
.It Ic \&?
Display the help screen, including current settings for options, where applicable.
.It Ic C
Compact long urls to fit them on one line.
.It Ic s
Toggle mode of display for speed detail between current and average, current only and average only.
.It Ic o
Toggle connection sort order between size, current speed, average speed and max time.
.It Ic R
Toggle hosts showing mode between host name only, host ip only, both ip and host name.
.It Ic q
Quit
.Nm
.El
.Sh EXAMPLES
.Pp
List all currently active connections in interacive mode from 192.168.2.0/24 and 172.18.118.10 to a Squid proxy running at
mysquid.example.com, port 8080 using ZePasswd as cachemgr_passwd:
.Dl $ sqtop -h mysquid.example.com -port 8080 -p ZePasswd -H 192.168.2.0/24,172.18.118.10
.Sh DIAGNOSTICS
.Ex -std sqtop
.Sh SEE ALSO
The Squid homepage at:
.Pa http://www.squid-cache.org .
.Pp
The
.Nm sqtop
homepage at:
.Pa http://code.google.com/p/sqtop/ .
.Sh AUTHOR
.Nm sqtop
was written by
.An Oleg Palij <o.palij@gmail.com> .
.Pp
This man page was originally written by
.An Marco Steinbach <coco@executive-computing.de> .
